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Apache Cordova Development Guide helps people to learn Cordova step by step with a 
large number of samples. 


Apache Cordova is an open-source mobile development framework. It allows you to use 
standard web technologies such as HTML5, CSS3, and JavaScript for cross-platform 
development, avoiding each mobile platforms’ native development language. Applications 
execute within wrappers targeted to each platform, and rely on standards-compliant API 
bindings to access each device's sensors, data, and network status. The latest version of 
Cordova is v5.4.1. 


There is also a GitBook version of the book: http://waylau.gitbooks.io/cordova-dev-guide. 
Let's READ! 


(Apache Cordova 开发 指南 》， 中 文 ， 通 过 大 量 实例 ， 图 文 并 茂 帮 助 Cordova 初学 者 快速 
掌握 Cordova. 


Apache Cordova 是 跨 平 台 应 用 开发 解决 方案 ， 而 PhoneGap 就 是 Cordova 的 原始 版 本 和 最 
流行 的 发 布 。 包 括 : 


e 使 用 HTML, CSS 和 JS 开发 移动 端 应 用 

e 一 次 编码 支持 多 平台 编译 ， 其 中 包括 Amazon Fire OS, Android, BlackBerry, Firefox 
OS, iOS, Ubuntu, Windows Phone, Windows 等 

。 免费 上 且 开 源 


Cordova 的 最 新 版 本 是 5.4.1。 


本 书 业 余 时 间 所 著 ， 水 平 有 限 、 时 间 紧 张 ， 难 免 踊 漏 ， 欢 迎 指 正 ， 点 此 提问 。 感 谢 您 的 参 
5! 


+ HARA x Gl, TEhttps://github.com/waylau/cordova-dev-guide 的 samples 目录 下 。 ME 
录 开 始 阅读 吧 ! 另外 有 GitBook 的 版 本 方便 阅读 http://waylau.gitbooks.io/cordova-dev- 
guide。 


Contact 联系 作者 : 
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e www.waylau.com 


快速 开始 


本 文 介绍 了 如 何 用 Cordova 快速 构建 一 个 应 用 。 


= J+ 
43x Cordova 
Cordova 命令 行 运行 于 Node.js 环境 ， 可 以 通过 NPM， 进 行 安装 。 


$ npm install -g cordova 


注 : 国内 环境 下 ， 可 以 设置 NPM 镜像 ， 来 使 安装 加 速 。 参 见 《 加 速 npm》 


创建 项 目 


使 用 命令 行 创 建 一 个 空 项 目 。 切 换 到 任意 目录 下 ， 执 行 cordova create <path> 来 创建 项 目 ， 
本 例 的 项 目 名 称 为 cordova-getstarted 


$ cordova create cordova-getstarted 


添加 平台 


项 目 创 建 后 ， 切 换 到 项 上 目下， 执行 cordova platform add «platform name> 来 添加 你 所 期 望 构 
建 项 目的 平台 。 本 例 的 平台 是 browser , 即 在 浏览 器 中 运行 。 


执行 run cordova platform 可 以 看 到 所 能 执行 添加 的 平台 。 


$ cd cordova-getstarted 


$ cordova platform add browser 


~— 4L 
i5 fT app 
执行 cordova run «platform name> 即 可 。 


$ cordova run browser 





= = 
管理 员 : C:\Windows\system32\cmd.exe San | 


D:NworkspaceGithubNcordova-dev-guide“samples>cordova create cordova-getstarted 
Creating a new cordova project. 


D:NworkspaceGithubSNcordova-dev-guide“samples>cd cordova-getstarted 


D:NworkspaceGithubsScordova-dev-guide“samplesN“cordova-getstarted>cordova platform 
add browser 

Adding browser project... 

Running command: cmd “Zs /c "“"G:NJsers“âdministratorN.cordovaNlib“npm_ cache“cordo 

va-browser\4.6.@\package \bin\create.bat D:\workspaceGit hub\cordova—dev—guide \sam 


uw 


ples“cordova-getstarted“platforms“Nbrowser io.cordova.hellocordova HelloCordova 


Creating Browser project. Path: platforms \browser 

Discovered plugin "cordova-plugin-whitelist" in config.xml. Installing to the pr 
oject 

Fetching plugin “cordova-plugin-whitelist@1" via npm 

Installing “cordova-plugin-whitelist" for browser 


This plugin is only applicable for versions of cordova-android greater than 4.0. 
If you have a previous platform version, you do *not* need this plugin since th 
e whitelist will be built in. 


D:NworkspaceGithubScordova-dev-guide“samples“cordova-getstarted>cordova run brow 
ser 
Running command: cmd "/s /c “D: \workspaceGithub\cordova—dev—guide samples \cordov 


a-getstarted“platformsNbrowserNcordovaNrun.bat"'" 

Static file server running on port 80009 <i.e. http://localhost :8000> 
CTRL + C to shut down 

Static file server running @ http://localhost :8666/index.html 








浏览 器 会 自动 运行 ， 效 果 如 下 
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问题 


问题 1 : 报 “ 找 不 到 chrome” 错 误 


快速 开始 7 


EN EEG: C:\Windows\system32\cmd.exe -cordova run browser ta ele DG 
a 








lva-brouserNd4.0.0 package Nbin*screate.bat D: \workspaceGithub\cordova—dev—guide ^san 
ples \cordova-getstarted\platforms\browser io.cordova.hellocordova HelloCordova"" 


reating Browser project. Path: platforms \browser 
Discovered plugin "cordova-plugin-vhitelist" in config.xml. 
oject 
Fetching plugin "cordova 
Installing "cordova-pluc 


Installing to the pr 


This plugin is only appl 
If you have a previous 
whitelist will be bui] 


cmd "/s /c 


"D: \works paceGit hub\cordova-—dev—guide \samples \cordov 
—-getstarted\platforms \browser\cordova\run.bat"" 


Static file server running on port 8068 Ci.e. 
TRL + C to shut down 

Static file 
TRL + C to shut down 


xecuting command: cmd Ac start "*" 


http://localhost:800n> 


server running @ http://localhost :8666/index.html 


chrome —--user-data-dir-ZTEMPz*stemp chrome use 
mr data dir for cordova http://localhost :8666/index.html 


解决 方法 1 : 安装 chrome 浏览 器 即 可 。 


wu 


解决 方法 2 : JE chrome 浏览 器 网 址 访问 http://localhost:8000/index.html 即 可 


Ym A 


e 见 https://github.com/waylau/cordova-dev-guide BY samples 目录 下 cordova-getstarted 
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Apache Cordova 是 开源 的 移动 开发 框架 。 人 允许 你 使 用 标准 的 web FRA, HO HTML5, CSS3 
和 JavaScript 来 构建 跨 平台 的 开发 ， 从 而 避免 使 用 原生 的 开发 语言 。 应 用 针对 每 个 平台 进行 
包装 内 执行 ， 并 依靠 符合 标准 的 API 绑 定 来 访问 不 同 设备 的 传感器 ， 数 据 和 网 络 状态 


Apache Cordova 在 2012 年 10 月 成 为 Apache Software Foundation (ASF) 的 顶级 项 目 ， 在 
Apache License v2.0 协议 下 继续 保持 开源 和 免费 。 


Apache Cordova 面向 的 用 户主 要 有 : 


e 移动 开发 者 ， 想 要 扩展 应 用 程序 到 多 个 平台 上 ， 而 不 必用 每 个 平台 的 语言 和 工具 集 重 新 
实现 它 。 

e WebFt RAR, HERBS Web 应 用 程序 打包 分 发 到 各 种 应 用 程序 商店 门户 。 

。 移动 开发 者 ， an 用 程序 与 可 以 访问 设备 级 的 API 的 WebView (特殊 的 浏览 器 窗 
口 ) 组 件 混合 开发 感 兴趣 ， 或 者 想 开 发 原生 与 WebView 组 件 之 间 的 插件 接口 。 


基本 组 件 


Cordova 应 用 程序 依赖 于 一 个 共同 的 config.xml 文件 ， 提 供 有 关 应 用 程序 的 信息 ， 并 指定 影 
响 它 的 工作 原理 ， 如 ， 是 否 响应 方向 的 变化 参数 。 该 文件 遵循 W3C 打包 的 Web 应 用 程序 ， 
或 插件 ， 规 范 。 


该 应 用 程序 本 身 是 一 个 网 页 ， 在 默认 情况 下 名 为 index.htm 的 本 地 文件 ， 即 无 论 引 用 CSS， 
JavaScript， 图 片 ， 多 媒体 文件 或 其 他 资源 都 需要 它 来 运行 。 该 应 用 程序 执行 的 本 地 应 用 程序 
包装 内 的 WebView。 


Cordova 使 得 WebView 可 提供 其 整个 用 户 界面 应 用 程序 。 在 某 些 平台 上 ， 它 也 可 以 是 混合 
原生 应 用 组 件 和 WebView 的 hybrid 应 用 。 ( 见 BRA WebViews 了 解 详细 信息 。) 


一 个 插件 接口 用 于 Cordova 和 原生 组 件 相互 通信 。 这 使 您 可 以 让 JavaScript 调用 原生 代码 。 
理想 情况 下 ，JavaScript API 面向 了 原生 代码 在 多 个 设备 平台 是 一 致 的 。3.0 版 本 ， 提 供 了 插 
件 绑 定 标准 的 设备 APIl。 第 三 方 插件 提供 额外 的 绑 定 功能 并 不 一 定 适用 于 所 有 平台 的 。 您 可 以 
在 插件 注册 表 中 找到 这 些 第 三 方 插 件 ， 并 可 以 在 你 的 应 用 程序 使 用 他 们 。 您 也 可 以 开发 自己 
的 插件 ， 参 考 插件 开发 指南 中 的 介绍 。 插 件 是 必要 的 ， 例 如 ，Cordova 和 自 定义 的 原生 组 件 
之 间 的 通信 。 


注意 : 3.0 版 本 ， 当 创建 一 个 Cordova 项 目 时 ， 并 默认 不 会 有 任何 插件 存在 ， 如 果 想 使 用 插 
件 ， 需 要 显示 添加 相应 的 插件 。 


Cordova 并 不 提供 任何 Ul 组 件 或 者 MV 框架 。 如 果 需 要 ， 需 要 自己 添加 第 三 方 包 。 
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开发 路 径 
3.0 版 本 ， 主 要 提供 2 种 开发 移动 应 用 的 流程 ， 他 们 各 有 优势 : 


e Cross-platform (CLI) workflow (BFE (STAM) 的 工作 流程 ) : 如 果 你 希望 你 的 
应 用 程序 ， 在 尽 可 能 多 的 不 同 的 移动 操作 系统 上 和 运行， 很 少 需要 特定 平台 开发 ， 那 么 你 
适合 使 用 此 工作 流程 。 该 工作 流程 围绕 cordova 工具 为 中 心 ， 就 是 3.0 中 引入 的 
Cordova CLl, CLl 是 一 个 高 层次 的 工具 ， 可 以 让 您 一 次 搭建 多 种 平台 项 目 ， 抽 象 出 许多 
低级 别 的 shell 脚本 的 功能 。 该 CLI 复制 一 套 通 用 的 网 络 资源 集注 入 到 子 目 录 每 个 移动 平 
台中 ， 使 得 任何 必要 的 配置 更 改 ， 就 运行 构建 脚本 生成 应 用 程序 二 进 制 文件 。 CLl 还 提 
供 了 通用 接口 应 用 到 你 的 应 用 程序 中 。 有 关 CLI 的 更 多 详细 信息 ， 请 参阅 命令 行 界 面 。 除 
非 你 有 使 用 以 平台 为 中 心 的 工作 流程 的 必要 ， 否 则 建议 使 用 跨 平 台 的 工作 流 。 
Platform-centered workflow (平台 为 中 心 的 工作 流程 ) : 如 果 你 想 专注 于 建立 一 个 应 用 
程序 的 单一 平台 ， 并 需要 能 够 在 较 低 的 水 平 ， 对 其 进行 修改 ， 请 使 用 此 工作 流程 。 您 需 
要 使 用 这 种 方法 ， 例 如 ， 如 果 你 希望 你 的 应 用 程序 混合 使 用 基于 Web 的 Cordova 组 件 定 
制 的 本 地 组 件 。 作 为 一 个 经 验 法 则 ， 如 果 你 需要 修改 SDK 中 的 项 目 ， 那 么 请 使 用 此 工作 
流程 。 该 工作 流 依赖 于 一 组 低级 别 的 shell 脚本 针对 每 个 支持 的 平台 ， 和 一 个 单独 的 
Plugman 工具 。 虽 然 你 可 以 使 用 这 个 流程 来 构建 跨 平台 的 应 用 程序 ， 但 是 比较 困难 ， 
为 缺乏 一 个 更 高 级 别 的 工具 ， 来 适应 独立 的 构建 周期 和 不 同 平台 的 插件 更 新 。 不 过 ， 这 
个 工作 流程 让 您 可 通过 每 个 SDK 提供 的 开发 方案 更 多 的 机 会 ， 而 且 是 复杂 的 混合 应 用 程 
序 所 必 不 可 少 的 。 见 平台 开发 指南 了 解 更 多 详情 。 


当 第 一 次 开始 ， 最 容易 使 用 的 跨 平 台 的 工作 流程 来 创建 一 个 应 用 程序 。 然 后 如 果 你 需要 更 好 
地 控制 SDK ， 您 可 以 切换 到 以 平台 为 中 心 的 工作 流程 。 低 级 别 的 shell 工具 在 与 CLI 类 似 的 
单独 的 发 布 包 中 。 对 于 由 CLl 最 初生 成 的 项 目 ， 这 些 shell 工具 也 都 在 项 目的 


platforms/*/cordova 目录 中 找到 。 


注意 : 一 旦 你 从 CL 的 工作 流程 来 转 到 特定 于 平台 的 SDK 和 shell 工具 为 中 心 ， 你 不 能 转 回 
去 了 。 该 CU 维护 一 套 通 用 的 跨 平 台 的 源 代码 ， 基 于 它 来 改写 特定 平台 的 源 代码 。 为 了 保护 
您 对 特定 平台 的 资源 的 任何 修改 ， 你 需要 切换 到 该 平台 为 中 心 的 shell 工具 ， 依 赖 于 特定 平台 
的 源 代码 而 忽略 了 跨 平台 的 源 代 码 。 


安装 Cordova 


不 同 的 流程 有 不 同 的 安装 方式 : 


e Cross-platform workflow: 见 命令 行 界面 
e Platform-centered workflow: 见 平台 开发 指南 


安装 之 后 ， 建 议 你 针对 你 需要 开发 的 平台 ， 对 照 平台 开发 指南 。 同 时 建议 你 查看 隐私 指南 ， 
安全 指南 ， 以 及 后 续 步 又 。 对 于 配置 Cordova， 请 参阅 config.xml 文件 。 对 于 从 JavaScript 
一 个 访问 设备 上 的 本 地 男 数 ， 请 参考 插件 APl。 
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MPTE (CLl) 


本 文 介绍 如 何 使 用 命令 行 界面 (CLI) 创建 应 用 程序 ， 并 将 它们 部 署 到 各 种 原生 移动 平台 。 这 
个 工具 允许 你 创建 新 的 项 目 ， 在 不 同 的 平台 构建 ， 并 运行 在 实际 设备 或 仿真 器 中 。 CLl 是 用 
于 在 概述 中 描述 的 跨 平台 的 工作 流 的 主要 工具 。 当 然 ， 你 也 可 以 使 用 CLI 来 初始 化 项 目 代 
码 ， 然 后 切换 到 不 同 的 平台 的 SDK 和 shell 工具 作为 后 续 发 展 。 


— e a E 

Alte 

使 用 CLI 前 ， 需 安装 目标 平台 的 SDK 。 ( 详 见 平台 开发 指南 ) 
CLI 支持 平台 情况 : 


e iOS (Mac) 

e Amazon Fire OS (Mac, Linux, Windows) 
e Android (Mac, Linux, Windows) 

e BlackBerry 10 (Mac, Linux, Windows) 

e Windows Phone 8 (Windows) 

e Windows (Windows) 

e Firefox OS (Mac, Linux, Windows) 


注 : 对 于 只 支持 Windows 的 平台 ， 可 以 在 Mac 机 子 上 运行 Windows MEDAL, RAW SA 
形式 运行 Windows。 详 见 Windows Phone 8 平台 指南 和 Windows 平台 指南 


安装 Cordova CLI 


安装 Cordova CLl 步骤 如 下 : 


1. 下 载 安 装 Node.js 

2. 下 载 安装 git 客户 端 。 由 于 被 墙 ， 国 内 用 户 从 官网 下 载 困难 ， 可 异步 至 Git for Windows 
国内 下 载 站 

3. 使 用 nmn 安装 cordova 模块 。 国 内 用 户 可 以 通过 设置 镜像 来 加 速 安 装 ， 详 见 加 速 npm 


对 于 OS X fll Linux: 


$ sudo npm install -g cordova 


对 于 Windows: 


C:\>npm install -g cordova 


创建 应 用 
切换 到 源 代码 的 目录 ， 然 后 运行 命 售 ， 如 下 所 示 : 


$ cordova create hello com.waylau.cordova.hello HelloWorld 


这 可 能 需要 一 些 时 间 命 令 完 成 ， 请 耐心 等 待 。 命 令 行 -d 选项 会 显示 进度 信息 。 


第 一 个 参数 hello 指定 你 的 项 目 要 生成 的 一 个 目录 。 这 个 目录 原来 不 存在 ，Cordova 会 为 您 
创建 它 。 其 子 目 录 ww 容纳 您 的 应 用 程序 的 主页 ， Mes css , js 和 img 的 各 种 资源 ， 
遵循 共同 的 Web 开发 文件 命名 约定 。 这 些 资源 将 被 存储 在 设备 上 的 本 地 文件 系统 ， 而 不 是 在 
远程 服务 上 。 该 config.xml 文件 中 包含 有 需要 生成 和 分 发 应 用 程序 的 重要 元 数据 。 


第 二 个 参数 输入 com.waylau.cordova.hello 提供 了 一 个 项 目的 反 向 域名 风格 的 标识 。 此 参数 
是 可 选 的 ， 如 果 省 略 该 参数 ， 则 必须 省 略 第 三 个 参数 。 您 可 以 之 后 在 config.xml 文件 编辑 这 
个 值 ， 但 建议 您 一 开始 就 选择 合适 的 值 ， 因 为 config.xml 生产 代码 会 用 到 这 个 值 ， 就 像 
Java 的 包 名 一 样 。 若 不 设置 此 值 ， 则 默认 值 是 io.cordova.hellocordova 。 


第 三 个 参数 的 HelloWorld 提供 了 应 用 程序 的 显示 标题 。 此 参数 是 可 选 的 。 您 可 以 之 后 
在 config.xml 文件 编辑 这 个 值 ， 但 建议 您 一 开始 就 选择 合适 的 值 ， 因 为 config.xml 生产 代 
码 会 用 到 这 个 值 ， 就 像 Java 的 包 名 一 样 。 若 不 设置 此 值 ， 则 默认 值 


是 io.cordova.hellocordova o 默认 值 是 HelloCordova o 


添加 平台 


所 有 后 续 命令 都 需要 在 项 目的 目录 下 ， 或 者 在 其 范围 内 的 任何 子 目 录 中 运行 : 


$ cd hello 


在 您 可 以 构建 项 目前 ， 你 需要 指定 一 组 目标 平台 。 您 运行 这 些 命令 的 能 力 取决 于 你 的 机 器 是 
否 支持 每 个 SDK， 以 及 是 否 已 经 安装 每 个 SDK, E 运行 : 

cordova platform add ios 

cordova platform add amazon-fireos 

cordova platform add android 

cordova platform add blackberry10 


€ 0 FF 0 


cordova platform add firefoxos 


Windows 运行 ， 其 中 wp 是 指 不 同 版 本 的 Windows Phone 操作 系统 的 : 


$ cordova platform add wp8 

$ cordova platform add windows 

$ cordova platform add amazon-fireos 
$ cordova platform add android 

$ cordova platform add blackberry10 
$ cordova platform add firefoxos 


查看 当前 支持 的 平台 : 


$ cordova platforms ls 


(注意 platform 和 platforms 的 命令 是 同 义 的 。 ) 


运行 下 列 命令 的 代名词 ， 移 除 一 个 平台 : 


$ cordova platform remove blackberry10 
$ cordova platform rm amazon-fireos 
$ cordova platform rm android 


(注意 remove 和 rm 的 命令 是 同 义 的 。 ) 


运行 命令 添加 或 删除 平台 ， 会 影响 了 项 目的 platforms 目录 ， 该 目录 下 为 每 个 指定 的 平台 显 
示 其 子 目录 的 内 容 。 ww 的 源 目录 转载 到 每 个 平台 的 子 目 录 中 ， 例 如 platforms/ios/ww 或 
platforms/android/assets/www 。 由 于 CLl 会 不 断 地 从 源 ww 复制 文件 ， 你 应 该 只 编辑 这 些 
源 文件 ， 而 不 是 那些 platforms 下 的 子 目录 。 如 果 您 使 用 的 版 本 控制 软件 ， 你 应 该 把 这 个 源 
www 文件 夹 ， 随 着 merges 文件 夹 一 起 添加 到 你 的 版 本 控制 系统 。 (关于 merges 文件 夹 的 
更 多 信息 ， 可 以 在 下 面 “ 使 用 merges 自 定义 每 个 平台 ”中 找到 ) 


SEED: 当 使 用 CLl 来 构建 应 用 程序 ， 你 不 应 该 在 /platforms/ 目录 编辑 任何 文件 ， 除 非 你 知 
道 自 己 在 做 什么 ， 或 者 说 明文 件 另 有 说 明 。 当 应 用 程序 构建 或 者 插件 准备 重新 安装 时 ， 该 目 
录 中 的 文件 是 经 常会 被 覆盖 的 。 


如 果 你 意识 到 了 这 点 ， 你 可 以 使 用 一 个 SDK， 如 用 Eclipse 或 Xcode 来 打开 你 创建 的 项 目 。 
您 将 需要 从 /platforms/ 目录 下 打开 资源 来 开发 SDK。 这 是 因为 SDK 特 定 的 元 数据 文件 存储 
在 相应 的 /platforms/ 子 目 录 中 。 (请 参阅 平台 开发 指南 了 解 如 何在 每 个 IDE 中 开发 应 用 程 
序 。) 如 果 你 只 是 想 用 CLl 初始 化 一 个 项 目 ， 然 后 切换 到 SDK 的 原生 工作 ， 那 么 请 使 用 此 方 
法 。 


如 果 你 想 在 整个 开发 周期 使 用 跨 平 台 的 工作 流 方法 (CLI) ， 请 继续 往 下 阅读 。 


构建 应 用 程序 


默认 的 ， cordova create 脚本 将 会 创建 一 个 基于 web 应 用 程序 的 骨架 ， 主 页 
是 www/index. html 文件 。 


和 迭代 的 构建 程序 ， 运 行 


$ cordova build 


可 以 制定 构建 的 平台 


$ cordova build ios 


cordova build 是 下 面 命 令 的 简化 


$ cordova prepare ios 
$ cordova compile ios 


在 这 种 情况 下 ， 一 旦 运行 了 prepare ， 你 可 以 用 茶 果 的 Xcode 的 SDK， 以 替代 修改 和 编译 
Cordova 生成 的 platforms/ios 特定 于 平台 的 代码 。 您 可 以 使 用 同样 的 做 法 在 其 他 平台 上 娘 
SDK 中 。 


在 模拟 器 或 者 设备 上 测试 应 用 


SDK 为 移动 平台 往往 捆绑 模拟 器 来 执行 设备 的 图 像 ， 这 样 就 可 以 从 主屏 幕 馈 动 应 用 程序 ， 查 
看 它 是 如 何 与 众多 平台 功能 进行 交互 的 。 运 行 如 下 命令 ， 在 特定 平台 构建 应 用 ， 坦 看 在 模拟 
器 中 执行 效果 : 


$ cordova emulate android 


一 些 移动 平台 上 在 默认 情况 下 会 模拟 一 个 特定 的 设备 ， 比 如 IOS 项 目 默认 是 iPhone。 对 于 其 
他 平台 ， 您 可 能 需要 首先 将 设备 与 模拟 器 相关 联 。 


注 : 模拟 器 的 支持 目前 不 适用 于 Amazon Fire OS, 


(请 参阅 平台 开发 指南 了 解 详 细 信息 。) 例如 ， 您 可 以 先 运行 android 命令 来 启动 Android 
SDK， 然 后 运行 特定 设备 的 图 像 ， 而 根据 它 的 默认 行为 启动 它 : 


Settings 
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或 者 ， 你 可 以 将 手机 插入 电脑 ， 并 直接 测试 应 用 程序 : 


$ cordova run android 


在 执行 上 述 命令 前 ， 先 要 在 设备 上 做 设置 。 在 Android 和 Amazon Fire OS 上 , FEA E 
用 “USB debugging’ t m. 请 参阅 平台 开发 指南 了 解 各 个 平台 的 设置 。 


添加 插件 


插件 ， 可 以 使 应 用 获得 与 设备 级 别 交流 的 能 力 ， 提 供 了 原生 组 件 的 接口 。 你 可 以 自己 设计 插 
件 ， 如 ， 设 计 一 个 混合 了 Cordova WebView 和 原生 组 件 的 hybrid 应 用 ( 详 见 * BRA 
WebViews 和 插件 开发 指南 ) 


3.0 版 本 后 ， 创 建 一 个 Cordova 是 不 会 存在 任何 插件 的 ， 你 需要 按照 需要 显示 的 添加 插件 。 


可 以 在 http://plugins.cordova.io/ 查找 插件 ， 其 中 也 包含 第 三 方 的 插件 。CLI 也 能 支持 插件 的 
查找 。 例如 使 用 关键 字 bar. code 进行 查找 。 


$ cordova plugin search bar code 


com.phonegap.plugins.barcodescanner - Scans Barcodes 


如 果 只 是 使 用 关键 字 bar ， 则 查找 结果 为 


cordova-plugin-statusbar - Cordova StatusBar Plugin 


cordova plugin add 命令 是 用 来 添加 插件 的 ， 比如 


。 基本 设备 信息 (设备 API): 


A 


cordova plugin add cordova-plugin-device 


。 网 络 连接 和 电池 事件 : 


€ 


cordova plugin add cordova-plugin-network-information 


€ 


cordova plugin add cordova-plugin-battery-status 


* 加 速度 计 ， 指 南 针 ， 和 地 理 位 置 : 


€ 


cordova plugin add cordova-plugin-device-motion 


€ 


cordova plugin add cordova-plugin-device-orientation 


€ 


cordova plugin add cordova-plugin-geolocation 


* 相机 ， 媒 体 播 放 和 捕捉 : 


€ 


cordova plugin add cordova-plugin-camera 


€ 


cordova plugin add cordova-plugin-media-capture 


€ 


cordova plugin add cordova-plugin-media 


在 设备 或 者 网 络 上 访问 文件 (File API): 


€ 


cordova plugin add cordova-plugin-file 


A 


cordova plugin add cordova-plugin-file-transfer 


。 通过 对 话 框 或 振动 通知 


€ 


cordova plugin add cordova-plugin-dialogs 


€ 


cordova plugin add cordova-plugin-vibration 


e 联系 方式 : 


€ 


cordova plugin add cordova-plugin-contacts 


e 全 球 化 : 


€ 


cordova plugin add cordova-plugin-globalization 


e JF: 


A 


cordova plugin add cordova-plugin-splashscreen 


e 打开 一 个 新 的 浏览 器 窗口 (InAppBrowser): 


A 


cordova plugin add cordova-plugin-inappbrowser 


。 控制 台 调 试 : 


€ 


cordova plugin add cordova-plugin-console 


È : CLl 增加 适合 各 个 平台 的 插件 代码 。 如 果 你 想 开 发 具有 较 低 级 别 的 she | 工具 或 平台 的 
SDK， 你 需要 运行 Plugman 工具 来 为 每 个 平台 单独 添加 的 插件 。 【〔 请 参阅 使 用 Plugman 来 
管理 插件 。) 


plugin ls (或 plugin list , plugin ) 查看 当前 已 安 装 装 的 插件 。 以 唯一 标识 做 为 显示 : 


$ cordova plugin ls # or ‘plugin list' 
[ 'cordova-plugin-console' ] 


移 除 时 ， 也 用 唯一 标识 来 移 除 


$ cordova plugin rm cordova-plugin-console 
$ cordova plugin remove cordova-plugin-console # same 


可 以 批量 添加 或 者 移 除 : 


$ cordova plugin add cordova-plugin-console cordova-plugin-device 


高 级 插件 选项 
添加 插件 时 ， o 制定 版 本 : 


$ cordova plugin add cordova-plugin-console@latest 
$ cordova plugin add cordova-plugin-consoleâ0.2.1 


JE registry.cordova.io 注册 的 插件 ， 也 从 其 他 git 库 添 加 : 


$ cordova plugin add https://github.com/apache/cordova-plugin-console.git 


# 来 指定 一 个 标签 (tag) 


$ cordova plugin add https://github.com/apache/cordova-plugin-console.git#r0.2.0 


或 者 一 个 分 支 : 
$ cordova plugin add https://github.com/apache/cordova-plugin-console.git#CB-8438cordova- 
a] ÁE) 


或 者 是 一 个 提交 : 





$ cordova plugin add https://github.com/apache/cordova-plugin-console.git#f055daec45575bf 
«| —— EN 
如 果 插 件 (以 及 plugin.xml 文件 ) ， 是 在 git 库 的 子 上 目录， 使 用 : 





$ cordova plugin add https://github.com/someone/aplugin.git#: /my/sub/dir 


当然 也 能 做 如 下 合并 : 


$ cordova plugin add https://github.com/someone/aplugin.gitfr0.0.1:/my/sub/dir 


或 者 ， 指 定 一 个 包含 plugin. xml 文件 的 本 地 插件 目录 : 


$ cordova plugin add ../my_plugin_dir 


使 用 merges 自 定 义 每 个 平台 


虽然 Cordova 让 您 可 以 轻松 地 部 署 应 用 程序 在 许多 不 同 的 平台 上 ， 有 时 你 需要 添加 一 些 自 定 
义 功 能 。 在 这 种 情况 下 ， 你 不 希望 修改 各 种 platforms 目录 下 的 ww 目录 中 的 源 文 件 ， 因 为 
他 们 经 常会 被 顶级 ww 目录 的 跨 平 台 源 所 取代 。 


取而代之 的 是 ， 顶 层 merges 目录 提供 指定 资源 来 部 署 在 特定 平台 上 的 地 方 。 merges 镜像 中 
的 每 个 特定 平台 的 子 目 录 反 映 了 ww 源 代 码 树 的 目录 结构 ， 使 您 能 够 覆盖 或 根据 需要 添加 文 
件 。 例 如 ， 下 面 演示 了 如 何 使 用 merges 以 提高 Android 和 Amazon Fire OS 设 各 的 默认 字体 
大 小 : 


e 编辑 www/index.html , 添加 额外 的 CSS 文件 overrides.css : 


<link rel="stylesheet" type="text/css" href="css/overrides.css" /> 


e 可 选 创 建 一 个 空 的 www/css/overrides.css 文件 ,应 用 于 非 Android 的 构建 , 防止 文件 丢失 
的 错误 。 

e 在 merges/android 下 创建 一 个 css 子 目录 ， 再 加 入 相应 的 overrides.css 文件 。 
在 www/css/index.css 中 指定 的 字体 大 小 ， 例 如 : 


body { font-size:14px; } 


在 重 构 项 目 中 ，Android 版 本 采用 了 自 定义 字体 大 小 ， 而 其 他 的 维持 不 变 。 


还 可 以 使 用 的 merges 来 添加 不 存在 于 原始 ww 目录 中 的 文件 。 例 如 ， 一 个 应 用 程序 可 以 将 一 
个 “后 退 按钮 "图形 插入 iOS 界 面 ， 存 储 在 merges/ios/img/back_button.png ， 而 Android 版 本 ， 
可 以 改 为 从 相应 的 硬件 按钮 事件 捕捉 [backbutton] 


(..7../cordova/events/events.backbutton.html) o 
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遇 到 问题 ， 请 呼唤 “帮助 "。 执 行 : 


$ cordova help 
$ cordova # same 


此 外 ， 你 可 以 得 到 一 个 更 详细 的 帮助 。 例如 


$ cordova run --help 


info 命令 产生 的 潜在 有 用 的 信息 ， 如 当前 已 安装 的 平台 和 插件 ， 每 个 平台 SDK 版 本 ，CLI 
和 Node.js 的 版 本 信息 列表 : 


$ cordova info 


它 既 在 屏幕 上 展示 信息 ， 并 输出 到 本 地 info.txt。 


注 : 目前 ， 仅 适用 于 iOS 和 Android 平台 的 详细 信息 。 


更 新 Cordova 和 你 的 项 目 
使 用 如 下 命令 更 新 cordova : 


$ sudo npm update -g cordova 


安装 特定 版 本 


$ sudo npm install -g cordova@3.1.0-0.2.0 


运行 cordova -v 来 查看 当前 运行 的 版 本 ， to see which version is currently running. 运行 
npm info 来 获取 当前 版 本 以 及 可 用 版 本 的 信息 : 


$ npm info cordova 


Cordova 3.0 是 支持 本 节 所 述 的 命令 行 界面 的 第 一 个 版 本 。 如 果 您 是 从 之 前 的 版 本 更 新 到 
3.0， 则 需要 如 上 所 述 创 建 一 个 新 的 项 目 ， 那 么 旧 的 应 用 程序 的 资源 复制 到 项 层 ww BR. A 
关 升 级 到 3.0 的 进一步 的 细节 ， 参 考 平 台 开 发 指南 。 一 旦 您 升级 到 cordova 的 命令 行 界面 ， 
并 使 用 npm update 保持 同步 。 


Cordova 3.0+ 可 能 仍然 会 有 各 种 变化 ， 包 括 项 目 级 目录 结构 和 其 他 依赖 。 在 运行 nm 命令 来 
更 新 Cordova 本 身后 ， 你 可 能 需要 确保 项 目的 资源 是 符合 最 新 版 本 的 要 求 。 运 行 命 售 ， 如 
F: 


$ cordova platform update android 
$ cordova platform update ios 
ana (Og 


i A 


e 本 文 所 用 源码 ， 见 https://github.com/waylau/cordova-dev-guide 的 samples 目录 下 
hello 


平台 开发 指南 


Cordova 支持 如 下 平台 : 


e Amazon Fire OS 
e Android 

e BlackBerry 10 

e Firefox OS 

e iOS 

e Ubuntu 

e Windows Phone 8 
e Windows 

e Tizen 


开发 工具 和 每 个 移动 平台 设备 API 的 最 新 的 平台 支持 情况 ， 可 参见 
http://cordova.apache.org/docs/en/latest/guide/support/index.html。 这 里 列 出 的 设备 API 是 
核心 插件 提供 的 ， 其 他 API 可 通过 第 三 方 插 件 提供 。 


平台 开发 


首先 安装 CLl， 参 见 命 命 行 界面 (CLI) o 
其 次 ， 针 对 不 同 的 平台 ， 需 要 安装 相应 的 SDK., 


下 面 列 出 的 每 个 平台 的 指南 会 告诉 你 如 何 设置 每 个 平台 的 开发 环境 : 从 哪里 获得 SDK， 如 何 
设置 设备 模拟 器 ， 如 何 连 接 设 备 直接 测试 ， 以 及 如 何 管理 签名 密 钥 的 要 求 。 其 他 指南 提供 了 
Gh 的 独特 的 配置 选项 ， 说 明 如 何 添加 插件 ， 如 何 升级 每 个 平台 以 及 特定 平台 的 命 

兮 行 工 具 ， 作 为 一 个 低级 别 的 cordova 命令 行 工具 的 替代 。 


Android 平台 


本 文 将 介绍 了 如 何 设置 SDK 环境 来 部 署 Cordova 应 用 到 Android 设备 上 ， 以 及 在 你 的 开发 
流程 中 如 何 选择 使 用 Android 命令 行 工 具 。 不 管 你 是 以 平台 为 中 心 的 工作 流程 还 是 跨 平 台 
(命令 行 界 面 ) 的 工作 流程 都 需要 安装 Android SDK. 


需求 及 支持 


Cordova 开发 Android 需要 Android SDK， 可 以 安装 在 OS X, Linux 或 Windows 操作 系统 。 
详 见 Android SDK 系统 需求 . 


Cordova 支持 Android 4.0.x (Android API 14 开始 ) 及 更 高 版 本 。 原 则 是 ，Cordova 不 再 支 
Rr 市 场 占有 率 少 于 5% 的 Android 版 本 (可 参见 Goolge Aix) > Android 版 本 早 于 Android 
API 10 及 3.x 版 本 占有 率 少 于 590, 


安装 Java Development Kit (JDK) 


安装 JDK 7 或 更 高 版 本 。 


Windows 系统 ， 需 设置 Java Home 值 为 JDK 的 安装 路 径 。 如 ， c:\Program 
Files\Java\jdk1.7.0_75 ) 


安装 Android SDK 


安装 Android Stand-alone SDK Tools 或 Android Studio, 若 需 要 开发 新 的 Cordova 的 
Android 插件 ， 或 者 使 用 原生 工具 来 运行 或 者 调试 Android 平台 ， 那 么 选择 Android Studio。 
否则 Android Stand-alone SDK Tools 足够 用 了 。 


需要 将 SDK 的 tools 和 platform-tools 目录 放 到 你 的 PATH FH, 


e Mac E Linux : 修改 ~/.bash_profile 文件 ， 添 加 SDK 安 装 信息 ， 如 下 : export 
PATH=${PATH} : /Development/android-sdk/platform-tools:/Development/android-sdk/tools 
e Windows : 修改 环境 变量 PATH , WI SDK 安 装 信息 ， 如 下 : ;C:NDevelopmentNandroid- 


sdk\platform-tools;C:\Development\android-sdk\tools 


安装 SDK 包 


HRS) 
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打开 Android SDK Manager (例如 ， 通 过 终端 : android ) 安装 如 下 内 容 : 


e Android 5.1.1 (API 22) platform SDK 
e Android SDK Build-tools version 19.1.0 or higher 


e Android Support Repository (Extras) 
2 $ n] LLB¥http://developer.android.com/sdk/installing/adding-packages.html 


配置 模拟 器 


Android sdk 没有 提供 默认 的 模拟 器 ， 需 要 自己 配置 。 命 令 行 运行 android ,点 击 Tools > 


4. D 
Manage AVDs 选择 Device Definitions 
Android Virtual Devices [EEOC Mee ———— 





List of known device definitions. This can later be used to create Android Virtual Devices. 
Device 
Galaxy Nexus 
Screen: 4.7", 720 x 1280, Normal xhdpi Clone... 
1024 MiB 
Delete... 
Create AVD... 


Nexus S 
Screen: 4.0”, 480 x 800, Normal hdpi 
343 MiB 


RAM: 
NexusS 
Screen: 4.0", 480 x 800, Normal hdpi 
RAM: 343 MiB 


Refresh 





Nexus One by Google 
Screen: 3.7", 480 x 800, Normal hdpi 
A user-created device definition. T A generic device definition. 


Il | qas] 


mit Create AVD ， 选 择 修改 名 称 ， 点 击 OK 
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wore [mm 














Device: Nexus S (4.0", 480 x 800: hdpi) $ 
Target: Android 4.2.2 - API Level 17 
CPU/ABI: ARM (armeabi-v7a) á 
Keyboard: M Hardware keyboard present 
Skin: ( Display a skin with hardware controls 
Front Camera: None | B : 
Back Camera: None $ 
Memory Options RAM: 343 VM Heap: 32 
Internal Storage (200 
SD Card: 「 
(sae: | 
Orie: "Browse... | 





a 和 m 
Emulation Options: (_] Snapshot (_ Use Host GPU 


Override the existing AVD with the same name 





(__Cancel_ | [0k 
that, AVD 将 出 现在 Android Virtual Devices 列表 中 : 


LOCC TE Device Definitions 





List of existing Android Virtual Devices located at /Users/sierra/.android/avd 


aa 


Android 4.2.2 ARM (armeabi-v7 


| Delete... | 
| Repair... | 
| Details... | 


| Start... | 





wv A valid Android Virtual Device. |) A repairable Android Virtual Device. 
3X An Android Virtual Device that failed to load. Click ‘Details’ to see the error. 


打开 模拟 器 ， 选 择 AVD 并 点 击 Start, 


平台 开发 指南 


了 à 2 3 Basic Control 


ADO 


WIDGETS Hardware Buttons 


OIN o5 NO 


3 = oe ws 
aim 


API Demos Browser Calculator Calendar 


-m ©) Foe = 
- -0 
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Camera Clock Custom Dev Settings 
Locale 
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使 用 virtual Machine Acceleration 可 以 加 速 虚拟 机 ， 获 得 更 好 的 体验 。 先 确认 你 的 系统 是 否 
支持 如 下 该 技术 : 


e Intel Virtualization Technology (VT-x, vmx) — 
e AMD Virtualization (AMD-V, SVM), 支持 Linux (Bi 2006 年 5 月 , 所 有 CPU AMD 包含 
AMD-V, 除了 Sempron) 


Windows 环境 下 ， 另 外 一 个 查找 Intel 处 理 器 支持 VT-x 技术 ， 是 通过 执行 Intel Processor 
Identification Utility ， 你 可 以 在 
下 载 该 工具 。 或 者 使 用 os Independent ,在 
下 载 该 工具 。 


执行 Intel Processor Identification Utility , 可 看 到 如 下 界面 
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Frequency Test CPU Technologies | CPUID Data | 
Intel& Processor Identification Utility 


Intel(R) Core(TM) i5-2540M CPU @ 2.60GHz 


Supporting Advanced Intel Processor Technologies 
Intel(R) Virtualization Technology 

Intel(R) Hyper-Threading Technology 

Intel(R) 64 Architecture 


Other Inte! Technologies Supported 

Enhanced Intel SpeedStep(R) Technology Intel(R) Advanced Vector Extensions 
Intel(R) SSE Intel(R) AES New Instructions 
Intel(R) SSE2 Intel VTx wth Extended Page Tables 
Intel(R} SSE3 

Intel(R) SSE4 


Infomation | 


Inte! processor numbers are not a measure of performance. Processor numbers differentiate features within each processor 
famiy. not across different processor families. See http://www intel. com/products/processor_number for details 





为 加 速 模拟 器 ， 下 载 至 少 一 个 intel x86 Atom System Image , Al Intel Hardware Accelerated 
Execution Manager (HAXM) 


打开 Android SDK Manager， 选 择 如 下 : 


Us Android 4.4 (API19) 


[m Documentation for Android SDK 19 a m Not installed 
E Samples for SDK 19 3 [C Not installed 
1. \Notinstalled 
($$ Google APIs 19 2 [| Not installed 
问 Sources for Android SDK 19 2 Notinstalled 
[a Extras 
E| E3 Android Support Repository 4 [| Not installed 
E3 Google Analytics App Tracking SDK 3 [| Not installed 
E3 Google Play services for Froyo 12 [7] Not installed 
E3 Google Play services 14 | |Notinstalled 
E| £3 Google Repository 5 [| |Notinstalled 
Google Play APK Expansion Library 3 [| |Notinstalled 
E3 Google Play Billing Library 5 [_] Not installed 
E Google Play Licensing Library 2 [T Not installed 
oogle Web Driver 2 (| Not installed 
3 (| Not installed 








下 载 后 ， 可 以 执行 Android SDK 中 的 extras/intel/Hardware_Accelerated_Execution Manager 
的 Intel 安装 包 ， 安 装 过 程 ， 遇 到 问题 ， 可 以 查阅 http://software.intel.com/en- 
us/android/articles/speeding-up-the-android-emulator-on-intel-architecture 


步骤 如 下 : 
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1. 安装 至 少 一 个 Intel x86 Atom System Image ,如 Intel Hardware Accelerated Execution 
Manager 

2. 运行 Intel RR, TE Android SDK 
的 extras/intel/Hardware_Accelerated_Execution_Manager 

3. 创建 新 的 AVD 目标 设 为 这 个 Intel image 

4. 当 启动 模拟 器 , 确保 加 载 HAX 模块 时 没有 错误 


创建 项 目 
创建 项 目 可 以 是 选择 CLl 或 者 是 Android 特有 的 shell 工具 。 使 用 CLI 如 下 : 


$ cordova create hello com.waylau.cordova.hello HelloWorld 
$ cd hello 

$ cordova platform add android 

$ ccordova prepare # or "cordova build" 


Unix, Windows 环境 下 ， 使 用 低级 别 的 shell 工具 : 


$ /path/to/cordova-android/bin/create /path/to/new/hello com.waylau.cordova.hello HelloWo 
C:\path\to\cordova-android\bin\create.bat C:\path\to\new\hello com.waylau.cordova.hello H 


Ee ad 





构建 项 目 
若 使 用 CLI， 则 项 目的 项 级 «e 目录 包含 的 就 是 源 文 件 。 构 建 执 行 如 下 : 


$ cordova build # build all platforms that were added 
$ cordova build android # build debug for only Android 

$ cordova build android --debug # build debug for only Android 

$ cordova build android --release # build release for only Android 


若 使 用 Android 特有 的 shell 工具 ， 则 有 些 不 同 。 生 成 项 目 ， 默 认 的 应 用 源码 是 在 
assets/www 子 目录 。 执 行 buid 将 会 清空 项 目 文件 ， 从 新 构建 。 以 下 是 Mac 和 Windows 下 
的 语法 ， 分 别 用 于 debug 和 release 


$ /path/to/project/cordova/build --debug 
C:\path\to\project\cordova\build.bat --debug 


$ /path/to/project/cordova/build --release 
C:\path\to\project\cordova\build.bat --release 


部 署 应 用 
使 用 CLI ， 部 署 应 用 到 模拟 器 或 者 设备 


$ cordova emulate android #to deploy the app on a default android emulator 
$ cordova run android --device #to deploy the app on a connected device 


否则 ， 使 用 备用 shell 界面 : 


$ /path/to/project/cordova/run --emulator 
$ /path/to/project/cordova/run --device 


可 以 使 用 cordova run android --list 查看 所 有 存在 的 目标 ， cordova run android -- 
target=target_name 来 运 行 特 定 的 模拟 器 或 者 是 设备 (如 cordova run android -- 


target="Nexus4 emulator" ) 
使 用 cordova run --help 来 查看 其 他 的 构建 和 运行 选项 。 
启动 应 用 ， 界 面 如 下 : 
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执行 run 它 默 认 就 build 了 项 目 ， 其 他 附加 参数 有 --debug, --release ,和 --nobuild , 
来 控制 是 否 需 要 重新 构建 


$ /path/to/project/cordova/run --emulator --nobuild 


Ahan 
生成 日 志 : 


$ /path/to/project/cordova/log 
C:\path\to\project\cordova\log. bat 


清除 项 目 : 


$ /path/to/project/cordova/clean 
C:\path\to\project\cordova\clean. bat 


ft SDK 中 打开 新 项 目 


当 项 目 中 已 经 添加 了 android 平台 ， 则 可 以 用 Android Studio 打开 : 


1. 启动 Android Studio 
2. 选择 Import Project (Eclipse ADT, Gradle, etc) 


ee Android Studio Setup Wizard 


Welcome to Android Studio 


Recent Projects Ouick Start 


Start a new Android Studio project 


No Project Open Yet 
pps Import an Android code sample 


ws 
[t Open an existing Android Studio project 
+ Check out project from Version Control 
ry Import project (Eclipse ADT, Gradle, etc.) 
> 


Configure 


EF? Docs and How-Tos 


1. 选择 android 平台 存储 的 位 置 ( your/project/platforms/android ) 
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Q9 € Select Eclipse or Gradle Project to Import - 
Select your Eclipse project folder, build.gradle or settings.gradle 








aenmx Oad Hide path 


/Users/sg/Development/helloCordova/platforms/android |i 


> (Sump 
v Users 
v [sg 
» [Applications 
» [Desktop 
v [Development 
» D3android-sdk 
> [3gradle-2.3 
v O helloCordova 
» [7hooks 
v [platforms 
> Massets 
> © cordova 
» [3CordovaLib 
> libs 
» platform. www 
Drag and drop a file into the space above to guickly locate it in the tree. 


© ( Cancel | o 


1. Gradle sync 的 问题 ， 直 接 回答 Yes 





此 时 ， 可 以 从 Android Studio 直接 构建 和 运行 应 用 了 


@ ®© @ (3) MainActivity.java - [android] - android - [~/Development/helloCordova/platforms/android] 
OHS <^ XT AR e HW (Pandroidiassembel-) > eo 9 E GOR 
Be? 


E3 android | a src [io > |) cordova > (^J hellocordova > c MainActivity 
































(Wi Android z| © = | #~ j- | © MainActivityjava x * 
o > TacCordovaLlib l/.../ eo 
v Caandroid i 3 
> Eo manifests : package io.cordova.hellocordova; 8 
a 
v java 2 
" i import ... 
E v Jio.cordova.hellocordova - 
E €. MainActivity ublic class MainActivity extends CordovaActivity m 
i 
íi » Dares @0verride d 
v Ca jniLibs public void onCreate(Bundle savedInstanceState) > 
b [assets í 8 
« © Gradle Scripts super.onCreate(savedInstanceState) ; 8 
t // Set by «content srce"index.html" /> in config 8 
z loadUrl(launchUrl); 
> } e 
z o 
a & 
" > 














Pb 4:Run @€5:Debug  ^* TODO j 6: Android Terminal = 0: Messages | Event Log Gradle Cc 


F 2 UTF 


更 多 细节 ， 可 以 参考 Android Studio Overview 和 Building and Running from Android Studio 
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Android shell 工具 


本 文 展示 了 如 何 使 用 以 平台 为 中 心 的 shel 工具 来 开发 Android 应 用 。 这 些 工具 允许 你 创建 、 
构建 和 运行 Android 应 用 。 


创建 项 目 
执行 create 命令， 在 Mac/Linux 和 Windows 的 语法 如 下 : 


$ /path/to/cordova-android/bin/create /path/to/project com.example.project_name ProjectNa 


C:\>\path\to\cordova-android\bin\create.bat \path\to\project com.example.project_name Pro 





构建 


执行 这 个 ， 先 会 清空 项 目 而 后 才 构 建 。 


Debug, 在 Mac/Linux 和 Windows 的 语法 如 下 : 
$ /path/to/project/cordova/build --debug 
C:\>\path\to\project\cordova\build.bat --debug 

Release, f£ Mac/Linux 和 Windows 的 语法 如 下 : 


$ /path/to/project/cordova/build --release 


C:\>\path\to\project\cordova\build.bat --release 


~— /一 
TIT 
run 命令 可 以 接受 如 下 可 选 参数 : 


. 指定 Target， 包括 : --emulator , --device , --target=<targetID> 
e 指定 Build, Cl: --debug, --release , EX --nobuild 


$ /path/to/project/cordova/run [Target] [Build] 


C:\>\path\to\project\cordova\run.bat [Target] [Build] 


请 确保 你 至 少 创建 一 个 Android Virtual Device,， 否 则 系统 会 提示 您 用 android MPR 
如 果 有 多 个 AVD 可 作为 一 个 目标 ， 系 统 会 提示 您 选择 一 个 。 默 认 情 况 下 运行 命令 检测 已 连接 
的 设备 ， 或 当前 正在 运行 的 模拟 器 (如 果 没 有 设 各 被 发 现 ) o 


对 应 用 签名 


Android 应 用 签名 的 需求 ， 可 查看 http://developer.android.com/tools/publishing/app- 
signing.html 


签名 一 个 应 用 ， 需 要 如 下 参数 : 


e Keystore (--keystore): 存储 key 的 编译 文件 的 路 径 

e Keystore password (--storePassword): keystore 密码 

Alias (--alias): 指定 用 于 签名 的 私 钥 id 

e Password (--password): 指定 密 钥 的 密码 

e Type of the keystore (--keystoreType): pkcs12, jks (默认 值 : 自动 检测 基于 文件 扩展 名 ) 


这 些 参数 可 以 在 build 或 run 脚本 里 面 指定 。 


另外 ， 您 也 可 以 使 用 ( --buildconfig ) 参数 在 构建 配置 文件 (buildjson) 中 指定 。 下 面 是 
一 个 构建 配置 文件 的 示例 : 


{ 
"android": { 
"debug": { 
"keystore": "..\android.keystore", 
"storePassword": "android", 


"alias": "mykey1", 
"password" : "password", 


"keystoreType": 
A 
"release": { 
"keystore": "..Nandroid.keystore", 
"storePassword": "", 
"alias": "mykey2", 
"password" : "password", 


"keystoreType": 


对 于 发 行 的 签名 ， 密 码 可 以 被 排除 在 外 ， 构 建 系统 会 发 出 提示 ， 要 求 输入 密码 。 


也 有 支持 混合 和 匹配 的 命令 行 参 数 和 build.json 文件 的 参数 。 命 令 行 参 数 的 值 将 获得 优先 权 。 
这 对 于 在 命令 行 上 指定 密码 是 有 用 的 。 


日 志 


$ /path/to/project/cordova/log 


C:\>\path\to\project\cordova\log. bat 


$ /path/to/project/cordova/clean 


C:\>\path\to\project\cordova\clean.bat 


使 用 Gradle 构建 


El cordova-android@4.0.0， 项 目的 构建 使 用 Gradle。 对 于 Gradle 的 学 习 ， 可 以 参阅 
(Gradle 2 FH P TRES) 。 


Gradle 属性 
属性 可 以 在 构建 时 自 定 义 : 
e cdvBuildMultipleApks (默认 : false) 


如 果 这 ae ， 那 么 多 个 APK 文件 ， 将 生成 : 每 一 个 库 项 目 (X86, ARMS) 支持 本 地 平台 
生成 一 个 。 这 可 能 是 重要 的 ， 如 果 你 的 项 目 使 用 了 大 量 本 地 库 ， 它 可 以 显 着 提高 所 产生 的 
APK "os 


如 果 没有 设置 ， 则 一 个 单个 的 APK 将 生成 可 以 在 所 有 设备 中 使 用 。 
e cdvVersionCode 
Æ% AndroidManifest.xml 中 的 versionCode, 
e cdvReleaseSigningPropertiesFile (默认 : release-signing.properties) 


包含 签名 信息 的 发 布 构建 的 .properties 文件 路 径 ， 类 似 于 : 


storeFile-relative/path/to/keystore.p12 
storePassword-SECRET1 

storeType-pkcs12 

keyAlias-DebugSigningKey 

keyPassword=SECRET2 

storePassword 和 keyPassword 是 可 选 的 ， 如 果 省 略 会 提示 。 


e cdvDebugSigningPropertiesFile (默认 : debug-signing.properties) 


和 cdvReleaseSigningPropertiesFile 一 样 ,但 是 为 了 调试 构建 。 在 需要 和 其 他 开发 者 分 享 签名 
密 钥 时 非常 有 用 


e cdvMinSdkVersion 

覆盖 AndroidManifest.xml 中 的 minSdkVersion。 当 创建 基于 SDK 版 本 多 个 APK 时 非常 有 用 
e cdvBuild ToolsVersion 

重 载 自动 检测 android.buildToolsVersion 值 
e cdvCompileSdkVersion 


重 载 自动 检测 android.compileSdkVersion 4 


扩展 build.gradle 


自 定义 build.gradle, 不 是 直接 编辑 ， 而 是 应 该 创建 一 个 同 级 文件 名 为 build-extras.gradle o 
该 文件 将 被 包含 在 主 build.gradle 。 下 面 是 一 个 例子 : : 


# Example build-extras.gradle 
# This file is included at the beginning of ~build.gradle~ 
ext.cdvDebugSigningPropertiesFile = '../../android-debug-keys.properties' 
# When set, this function allows code to run at the end of 'build.gradle 
ext.postBuildExtras = { 

android. buildTypes.debug.applicationIdSuffix = '.debug' 


注意 插件 也 可 以 包含 进来 ， 通 过 在 build-extras.gradle 文件 设置 : 


<framework src="some.gradle" custom="true" type="gradleReference" /> 


构建 示例 


export ORG_GRADLE_PROJECT_cdvMinSdkVersion=14 
cordova build android -- --gradleArg=-PcdvBuildMultipleApks=true 


Android 配置 


config.xml 文件 控制 应 用 在 各 个 应 用 和 CordovaWebView 实例 的 基本 设置 。 本 文 只 涉及 
Android 构建 部 分 。 详 见 config.xml 文件 。 


e KeepRunning (boolean, 默认 true ): 确定 项 目 是 否 在 触发 [pause] 
(../../../cordova/events/events.pause.html) 事件 后 在 后 台 运 行 。 设置 为 false 并 不 会 
在 [pause](../../../cordova/events/events.pause.html) 事件 后 杀 掉 应 用 ,应 用 程序 是 在 
后 台 而 只 是 暂停 cordova webview 的 执行 。 


<preference name="KeepRunning" value="false"/> 


*  LoadUrlTimeoutValue (数值 是 =P, 默认 值 是 20000 , 20 秒 ): 当 加 载 页 面 时 ， 超 时 会 抛 出 
2324 下 面 是 一 个 设置 为 10 秒 SAT 


«preference name-"LoadUrlTimeoutValue" value="10000"/> 


* splashScreen (string, 默认 是 splash ): 该 文件 减 去 其 在 res/drawable 目录 扩展 的 名 称 。 
各 种 资 资源 必 须 在 不 同 的 子 目 录 共 享 这 一 名 字 。 


<preference name="SplashScreen" value="mySplash"/> 


e SplashScreenDelay (数值 是 毫秒 , 默认 值 是 seee ) 闪 屏 图 像 显 示 的 时 间 。 


<preference name="SplashScreenDelay" value="10000"/> 


e InAppBrowserStorageEnabled (boolean, 默认 是 true ): 控制 InAppBrowser 默认 的 浏览 
打开 的 页 面 是 否 可 以 访问 相同 的 localStorage 和 WebSOL 存储 。 


<preference name="InAppBrowserStorageEnabled" value="true"/> 


e Loadingpialog (string, 默认 是 null ): 如 果 设 置 ， 加 载 应 用 程序 的 第 一 页 时 ， 对 话 框 显 示 
指定 的 标题 和 消息 ， 以 及 一 个 旋转 器 。 标 题 和 消息 之 间 用 逗号 分 离 出 来 ， 并 在 显示 对 话 
框 之 前 这 个 过 号 被 删除 。 


<preference name="LoadingDialog" value="My Title,My Message"/> 


LoadingPageDialog (string, 默认 是 null ): 5 LoadingDialog 类 似 ， 但 在 第 一 个 页 面 之 后 
加 载 所 有 页 面 


<preference name="LoadingPageDialog" value="My Title,My Message"/> 


Errorur1 (URL, 默认 是 _ null ): 如 果 设 置 ， 则 会 显示 一 个 错误 页 面 来 代替 "Application 
Error" xt 34E. 


«preference name-"ErrorUrl" value-"myErrorPage.html"/> 


Showritle (boolean, 默认 是 false ) 显示 标题 在 屏幕 上 方 


<preference name="ShowTitle" value="true"/> 


LogLevel (string, 默认 是 ERROR ): 设置 日 志 级 别 ， 值 包括 ERROR, WARN, INFO, DEBUG , 
和 VERBOSE . 

<preference name-"LogLevel" value="VERBOSE"/> 
SetFullscreen (boolean, 默认 是 false y 与 全 局 配置 文件 xnl 中 的 Fullscreen 参数 类 


似 。 该 属性 在 未 来 版 本 将 会 移 除 ， 不 推荐 使 用 


AndroidLaunchMode (string, 默认 是 singleTop ): 设置 Activity android:launchMode 属 
性 。 这 个 会 在 应 用 图 标 启 动 或 者 已 经 运行 在 运行 时 发 生变 化 ， 值 包括 standard , 


singleTop , singleTask , singleInstance . 


<preference name="AndroidLaunchMode" value-"singleTop"/> 


DefaultVolumestream (string, 默认 是 default , 在 cordova-android 3.7.0 版 本 加 入 ): 设置 

硬件 音量 按钮 链接 到 哪个 音量 。 软 认 情 况 下 ， 这 是 “cal" 链 接 到 手机 ， 而 “media" 链 接 的 是 
平板 电脑 。 设 置 “media” 到 你 的 应 用 程序 的 音量 按钮 将 会 随时 改变 媒体 音量 。 需 要 注意 的 
是 使 用 Cordova 的 媒体 插件 时 ， 当 任何 媒体 对 象 是 活动 时 ， 音 量 按键 会 动态 变化 ， 以 控 
制 媒体 音量 。 


OverrideuserAgent (string, 默认 不 设置 ): 如 果 设 置 ， 该 值 将 取代 webview 的 老 用 户 代 
理 。 从 应 用 程序 /浏览 器 请 求 远 程 页 面 时 ， 对 于 确定 该 请 求 是 有 用 的 。 请 谨慎 使 用 这 个 设 
置 ， 因 为 可 能 会 导致 与 Web 服务 器 的 兼容 性 问题 。 对 于 大 多 数 情况 下 ， 使 用 
AppendUserAgent 代替 。 


«preference name-"OverrideUserAgent" value="Mozilla/5.0 My Browser" /> 


e AppenduserAgent (string, 默认 不 设置 ): 如 果 设 置 ， 该 值 将 追加 到 的 webview HAH P 1X 
理 的 尾部 。 当 OverrideUserAgent 使 用 ， 该 值 将 被 忽略 。 


<preference name="AppendUserAgent" value="My Browser" /> 


Android 插件 


本 节 详 细 介 绍 了 如 何在 Android 平台 上 的 实现 原生 插件 代码 。 在 读 这 篇 文章 前 ， 请 参阅 应 用 
程序 插件 关于 插件 的 结构 和 共同 的 JavaScript 接口 的 概述 。 本 节 展 示 “ 回 声 " 插 件 示例 ， 来 实现 
Cordova webview 与 原生 平台 的 通信 交互 。 该 示例 也 可 见 CordovaPlugin.java. 


基于 Cordova-Android 的 Android 插件 ， 是 Android 的 WebView 与 连接 到 其 挂 匆 。 插 件 被 表 
示 为 在 config.xml 文件 类 的 映射 。 一 个 插件 至 少 有 一 个 Java 类 ， 是 继承 了 CordovaPlugin 

KK, HEU) execute 方法 之 一 。 作 为 最 佳 实践 ， 该 插件 还 应 该 处 理 任何 消息 的 插件 之 间 传 
递 的 [pause](../../../cordova/events/events.pause.html) 和 [resume ] 
(../../../cordova/events/events.resume.htm1) BA, HHA KN 运行 的 请 求 ， 后 台 活 动 ， 如 
媒体 播放 ， 监听 器 ， 或 内 部 状态 应 该 实现 onReset() 方法 为 好 。 它 在 WebView 导航 到 新 页 面 
或 刷新 时 执行 ， 从 而 重新 加 载 JavaScript。 


插件 类 映射 
插件 的 JavaScript 接口 使 用 cordova.exec 方法 如 下 : 


exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]); 


请 求 从 WebView 发 起 到 Android 端 ， 调 用 service 类 的 action ASK, 4555 args 数组 参 
数 。 


发 布 一 个 插件 ， 无 论 是 Java 文件 或 者 是 jar 文件 ， 插 件 必 须 在 你 的 Cordova-Android 应 用 的 
res/xml/config.xml 文件 指定 。 见 应 用 插件 如 何 使 用 plugin.xml 文件 来 插入 feature 元 素 : 


<feature name="<service_name>"> 
«param name="android-package" value="<full name_including_namespace>" /> 
</feature> 


service 名 称 在 JavaScript 的 exec 调用 中 相 匹 配 。 该 值 是 Java 类 的 完全 限定 命名 空间 的 标 
识 。 否 则 ， 该 插件 即使 可 以 编译 ， 仍 无 法 在 Cordova 使 用 。 


插件 的 初始 化 及 有 效 期 


插件 对 象 实例 由 每 个 webview 的 有 效 期 内 创建 。 插 件 不 会 初始 化 ， 直 到 第 一 个 引用 被 
JavaScript 调用 , 除非 config.xml 的 <param> 中 的 onload 的 name 属性 设置 为 "true", 
如 : 


<feature name="Echo"> 


<param name="android-package" value="<full_name_including_namespace>" /> 
<param name="onload" value="true" /> 
</feature> 


插件 的 initialize 方法 启动 如 下 : 


@Override 
public void initialize(CordovaInterface cordova, CordovaWebView webView) { 


super.initialize(cordova, webView) ; 
// your init code here 


编写 Android Java 插件 


插件 类 的 execute 方法 ， 实 现 方式 一 般 如 下 : 


@Override 


public boolean execute(String action, JSONArray args, CallbackContext callbackContext 
if ("beep".equals(action)) { 
this.beep(args.getLong(0)); 
callbackContext.success(); 
return true; 
} 
return false; // Returning false results in a "MethodNotFound" error. 


} 


EE) 





JavaScript exec 方法 的 action 参数 对 应 私有 类 的 可 选 参数 的 调用 。 


当 捕捉 异常 并 返回 错误 ，JavaScript 的 错误 应 该 尽 可 能 与 Java 异常 相 匹配 。 


线程 


插件 的 JavaScript 并 不 运行 在 webview 接口 的 主线 程 ， 而 是 运行 在 webcore 线程 的 
execute 方法 。 如 果 需 与 其 他 用 户 界面 交互 ， 使 用 方法 修改 如 下 : 


@Override 
public boolean execute(String action, JSONArray args, final CallbackContext callbackC 
if ("beep".equals(action)) { 
final long duration = args.getLong(0); 
cordova.getActivity().runOnUiThread(new Runnable() { 
public void run() { 


callbackContext.success(); // Thread-safe. 


3) 


return true; 


} 


return false; 


} 
sess bI a] 





当 不 需 在 主 界面 线程 运行 ， 又 不 想 阻 塞 webcore 线程 ， 使 用 如 下 : 


@Override 
public boolean execute(String action, JSONArray args, final CallbackContext callbackC 
if ("beep".equals(action)) { 
final long duration = args.getLong(0); 
cordova.getThreadPool().execute(new Runnable() { 
public void run() { 


callbackContext.success(); // Thread-safe. 


Jy); 


return true; 


} 


return false; 


} 





TAS DOR tJ 


如 果 插 件 需 额外 的 库 ， 需 要 在 config.xml 添加 ， 


方法 1 通过 Gradle 引用 ， 上 比如 : 


<framework src="com.android.support:support-v4:+" /> 


详情 可 参见 Gradle 的 依赖 管理 ， 参 考 《Gradle 2 用 户 指南 》 


方法 2 JAR 文件 替换 插件 的 文件 夹 使 用 lib-file 来 链接 ,比如 : 


<lib-file src-"src/android/libs/gcm.jar"/> 


用 此 方法 的 前 提 是 你 非常 清楚 你 特定 插件 的 依赖 jar 不 会 被 其 他 插件 所 使 用 ， 不 然 会 代码 构建 
的 问题 。 


Echo Android Plugin 示例 


本 例 演 示 JavaScript 接口 的 echo 功能 ， 使 用 plugin.xml 来 注入 feature 到 config.xml 
文件 : 


<platform name="android"> 
<config-file target="config.xml" parent="/*"> 
<feature name="Echo"> 
<param name="android-package" value="org.apache.cordova.plugin.Echo"/> 
</feature> 
</config-file> 
</platform> 


添加 src/org/apache/cordova/plugin/Echo.java 文件 : 


package org.apache.cordova.plugin; 


import org.apache.cordova.CordovaPlugin; 
import org.apache.cordova.CallbackContext; 


import org.json.JSONArray; 
import org.json. JSONException; 
import org.json.JSONObject; 


fa 

* This class echoes a string called from JavaScript. 
7 

public class Echo extends CordovaPlugin { 


@Override 
public boolean execute(String action, JSONArray args, CallbackContext callbackCon 
if (action.equals("echo")) { 
String message = args.getString(0); 
this.echo(message, callbackContext); 
return true; 


) 


return false; 


private void echo(String message, CallbackContext callbackContext) { 
if (message != null && message.length() > 0) { 
callbackContext.success(message) ; 
} else ( 
callbackContext.error("Expected one non-empty string argument."); 





文件 继承 CordovaPlugin ， Hex execute() 方法 ， 来 接收 exec() 的 消息 。 execute() 方 
法 首先 测试 action 的 值 ， 在 这 种 情况 下 ， 只 有 一 个 有 效 echo 值 。 任 何其 他 操作 都 返回 
false ， 并 导致 一 个 INVALID_ACTION 错误 ， 给 JavaScript 回调 。 


接 下 来 ， 该 方法 检索 使 用 args 对 象 的 getstring 方法 ， 指 定 传递 给 该 方法 的 第 一 个 参数 。 
值 传递 给 私有 ech 方法 后 ， 对 参数 进行 检查 ， 以 确保 它 不 是 null 或 空 字 符 串 ， 在 这 种 情 
M F callbackContext.error() 调用 JavaScript 的 错误 回调 。 如 果 各 种 检查 都 通 

it, callbackContext.success() 把 原始 message 字符 串 返 回 到 JavaScript 的 成 功 回调 作为 
参数 。 


Android 集成 


Android 功能 intent 允许 与 其 他 进程 进行 交互 。 插 件 访 问 CordovaInterface 对 象 ， 而 该 对 
象 可 以 访问 应 用 的 Android Activity 。 这 个 context 需要 和 启动 一 个 新 的 Android Intent o 
CordovaInterface 允许 插件 来 启动 一 个 Activity 用 于 义理 结果 ， 并 当 intent 返回 给 应 用 
时 设置 回调 插件 。 


Cordova 2.0 插件 不 能 直接 访 问 Context ,遗留 y ctx 成 员 不 再 推荐 使 用 。 所 有 的 ctx 方法 
存在 于 context ,所 以 getContext() 和 getActivity() 可 以 返回 所 需 的 对 象 。 


Android 权限 


Android 权限 是 在 安装 时 而 不 是 在 运行 时 的 进行 处 理 。 这 些 权限 需要 在 使 用 时 在 应 用 程序 中 声 
明 ， 并 且 这 些 权限 需要 被 添加 到 Android Manifest。 这 可 以 通过 使 用 在 config.xml 注入 在 
AndroidManifest.xml 文件 中 来 实现 这 些 权 限 。 下 面 的 示例 为 使 用 联系 人 权限 。 


<config-file target-"AndroidManifest.xml" parent="/*"> 
<uses-permission android:name="android.permission.READ_CONTACTS" /> 
</config-file> 


Android 权限 (Cordova-Android 5.0.x 及 跟 高 版 
本 ) 


Android 6.0 "Marshmallow" 引入 了 新 的 权限 模型 ， 可 以 在 需要 时 和 启动 后 者 关闭 权限 。 他 意味 
着 应 用 程序 义理 这 些 权限 更 改 必须 是 面向 未 来 的 ， 这 是 Cordova-Android 5.0 版 本 的 重点 。 


需要 在 运行 时 处 理 权限 可 以 在 Android 开发 者 文档 中 找到 。 
至 于 一 个 插件 而 言 ， 权 限 请 求 通过 权限 方法 ， 该 方法 的 签名 如 下 : 


cordova.regguestPermission(CordovaPlugin plugin, int requestCode, String permission); 
ab | 
为 减少 元 长 ， 标 准 的 做 法 是 分 配 一 个 本 地 静态 变量 : 
public static final String READ = Manifest.permission.READ_CONTACTS; 
同时 定义 一 个 请 求 编码 ， 如 下 : 


public static final int SEARCH_REQ CODE = 0; 


f£ exec 方法 ,权限 将 会 被 检查 : 


if(cordova.hasPermission(READ)) { 
search(executeArgs); 


} 


else 


{ 
getReadPermission(SEARCH_REQ_CODE); 


此 时 ， 我 们 只 需 调 用 reguestPermission: 


protected void getReadPermission(int requestCode) 


{ 


cordova.requestPermission(this, requestCode, READ); 


这 会 调用 activity 并 会 提示 要 求 权 限 。 若 用 户 有 权限 ， 则 结果 必须 被 
onReguestPermissionResult 方法 义理 。 这 是 每 个 插件 必须 履 盖 的 。 示 例如 下 : 


public void onRequestPermissionResult(int requestCode, String[] permissions, 
int[] grantResults) throws JSONException 


x 
for(int r:grantResults) 
t 
if(r -- PackageManager.PERMISSION DENIED) 
{ 
this.callbackContext.sendPluginResult(new PluginResult(PluginResult.Status.ER 
return; 
} 
} 
switch(requestCode) 
{ 
case SEARCH REQ CODE: 
search(executeArgs); 
break; 
case SAVE_REO CODE: 
save(executeArgs); 
break; 
case REMOVE REQ CODE: 
remove(executeArgs); 
break; 
} 
} 





权限 也 可 以 用 数组 形式 ， 下 面 是 Geolocation 插件 : 


String [] permissions = { Manifest.permission.ACCESS COARSE LOCATION, Manifest.permission 
‘| — BR 
当 ; 青 求 权限 时 ， 只 需 如 下 人 处理: 








cordova.requestPermissions(this, 0, permissions); 


这 就 要 求 在 数组 中 指定 权限 。 这 是 一 个 好 主意 ， 提 供 可 公开 访问 的 权限 数组 ， 因 为 这 可 以 由 
使 用 你 的 插件 作为 依赖 插件 ， 虽 然 这 不 是 必需 的 。 


调试 Android 插件 


Android 的 调试 可 以 使 用 Eclipse 或 Android Studio 来 完成 ， 虽 然 推荐 使 用 Android Studio. 
由 于 Cordova-Android 目前 用 作 一 个 库 项 目 ， 并 且 插 件 支 持 源 代码 ， 这 使 得 在 Cordova 应 用 
中 调试 Java 代码 就 像 是 原生 的 Android 应 用 。 


Android WebViews 


本 文 演示 了 如 何在 大 型 Android AEA, Ate Cordova-enabled WebView 2814. ART HEB 
件 之 间 如 何 交 互 ， 参 见 插件 开发 指南 。 


若 你 对 Android 还 不 熟悉 ， 可 以 先 参考 Android 平台 ， 并 安装 Android SDK. Cordova 1.9 F 
始 , Android 平台 依赖 cordovawebview 组 件 ,该 组 件 是 基于 cordovaActivity 组 件 构建 的 。 


1. 首先 确保 有 最 新 的 Cordova 的 发 布 包 ， 从 cordova.apache.org 下 载 ， 并 解压 Android 
包 。 


2. 切换 到 Android 包 的 /framework 目录 ， 并 运行 ant jar , 它 将 创建 Cordova .jar 文 
件 ， 格式 如 /framework/cordova-x.x.x.jar 


3. 拷贝 .jar 文件 到 Android 项 目的 /libs 目录 


4. 添加 如 下 /res/xml/main.xml 文件 ,设置 相应 的 layout height , layout width 和 id: 


«org.apache.cordova.CordovaWebView 
android:id-z"Q-id/tutorialView" 
android: layout_width="match_parent" 
android: layout_height="match_parent" /> 


5. 修改 activity 让 其 实现 cordovaInterface ， 它 会 实现 包含 的 方法 。 可 以 拷贝 自 
/framework/src/org/apache/cordova/CordovaActivity.java , 或 者 自己 实现 。 下 面 的 代码 片 
段 显 示 ， 依 赖 于 接口 上 的 基本 应 用 。 请 注意 引用 视图 id 与 上 面 显 示 的 XML 片段 指定 的 
id 属性 如 何 相 匹配 : 


public class CordovaViewTestActivity extends Activity implements CordovaInterface { 
CordovaWebView cwv; 
/* Called when the activity is first created. */ 
QOverride 
public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.main); 
cwv = (CordovaWebView) findViewById(R.id.tutorialView); 
Config.init(this); 
cwv.loadUrl(Config.getStartUrl()); 


二 n e LLLLVCIIZZZZZZIIZZJZAJTZJIAAZIZZZJA4U!T1TZMAMMZZZZLZZAZZZZZNOGNOSSIOSUSUS S] 
6. 若 应 用 使 用 了 摄像 头 ， 用 法 如 下 : 


7. 


ov 
pub 


} 
gaed 
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erride 
lic void setActivityResultCallback(CordovaPlugin plugin) { 
this.activityResultCallback = plugin; 


Launch an activity for which you would like a result when it finished. When this 
your onActivityResult() method is called. 


@param command The command object 
@param intent The intent to start 
@param requestCode The request code that is passed to callback to identify 


lic void startActivityForResult(CordovaPlugin command, Intent intent, int request 
this.activityResultCallback = command; 
this.activityResultKeepRunning = this.keepRunning; 


// If multitasking turned on, then disable it for activities that return results 


if (command != null) { 
this.keepRunning = false; 


// Start activity 


super.startActivityForResult(intent, requestCode) ; 


erride 


Called when an activity you launched exits, giving you the requestCode you starte 
the resultCode it returned, and any additional data from it. 


@param requestCode The request code originally supplied to startActivityFor 
allowing you to identify who this result came from. 

@param resultCode The integer result code returned by the child activity 1 

@param data An Intent, which can return result data to the caller (\ 


tected void onActivityResult(int requestCode, int resultCode, Intent intent) { 
super .onActivityResult(requestCode, resultCode, intent); 


CordovaPlugin callback = this.activityResultCallback; 
if (callback != null) { 
callback.onActivityResult(requestCode, resultCode, intent); 





最 后 ， 添 加 线程 池 ， 除 非 插件 没有 线程 来 运行 : 
@Override 
public ExecutorService getThreadPool() { 


return threadPool; 


8. 拷贝 应 用 的 HTML 和 JavaScript 文件 到 Android 项 目的 /assets/mw 目录 


9. 从 /framework/res/xml UN config.xml 文件 到 /res/xml 目录 


升级 Android 


本 文 介绍 了 如 何 修 改 Android 项 目 来 从 旧版 的 Cordova 升级 。 大 部 分 指令 适用 于 与 旧 的 
cordova CLl 工具 创建 的 项 目 。 有 关 CLI 内 容 ， 可 以 参阅 命令 行 界面 (CLl) 


升级 至 4.0.0 
升级 至 4.0.0 有 些 特殊 的 步骤 ， 首 先 ， 对 于 非 CLI 项 目 ， 运 行 


bin/update path/to/project 


对 于 CLl 项目: 
1. 升级 cordova CLl 版 本 ， 见 命令 行 界 面 (CLl) 


2. 在 现 有 的 项 目 中 运行 cordova platform update android o 


升级 Whitelist 
所 有 的 whitelist 功能 现在 都 通过 插件 实现 ， 当 升级 至 4.0.0 后 ， 将 不 会 受 whitelist 保护 。 
Cordova 有 2 个 whitelist 插件 ， 来 提供 不 同 级 别 的 保护 : 
1. cordova-plugin-whitelist 插件 (推荐 ) 
这 个 是 值得 推荐 的 ， 因 为 比 之 前 的 whitelist 版 本 更 加 安全 和 可 配置 。 


o 详 见 cordova-plugin-whitelist 
o 运行 : cordova plugin add cordova-plugin-crosswalk-webview 


2. cordova- plugin-legacy-whitelist 插件 


o 与 之 前 的 whitelist 版 本 类 似 ， 见 cordova-plugin-legacy-whitelist * 不 会 有 配置 上 的 变 
化 ， 但 比 推荐 的 插件 少 一 些 保 护 


9 运行 : cordova plugin add cordova-plugin-legacy-whitelist 
使 用 Crosswalk WebView 


默认 ， 应 用 继续 使 用 设备 提供 的 系统 WebView, BRK, (HA Crosswalk 插件 : 


cordova plugin add cordova-plugin-crosswalk-webview 


Ft #2 Splashscreen 插件 
若 想 使 用 闪 屏 ， 需 使 用 该 插件 ， 配 置 方法 没有 变 ， 只 需 如 下 方法 添加 插件 : 


cordova plugin add cordova-plugin-splashscreen 


其 他 旧版 升级 


可 参阅 http://cordova.apache.org/docs/en/latest/guide/platforms/android/upgrade.html 


fir A. WebViews 


966099966009 


Apache Cordova Development Guide. (Apache Cordova 开发 指南 》 


使 用 Plugman 来 管理 插件 


使 用 Plugman 来 管理 插件 
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